home *** CD-ROM | disk | FTP | other *** search
/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / umich / sound / players / naudio.lzh / naudio / doc / tutori_s.txt < prev   
Text File  |  1993-11-23  |  19KB  |  493 lines
  1.  
  2.  
  3. Einführung
  4.  
  5. NAUDIO   Die Samplelibrary Mulle KybernetiK
  6.  
  7.  
  8. Version 1.0
  9.  
  10.                   Copyright auf Dokumentation and Programmcode
  11.                            © 1993 Mulle KybernetiK
  12.  
  13.                   "Bang that bit that doesn't bang"
  14. Copyright 1993 Mulle KybernetiK
  15. Alle Rechte Vorbehalten.
  16.  
  17.  
  18. Das Werk einschließlich seiner Teile ist urheberrechtlich geschützt.
  19.  
  20. Das vorliegende Werk darf, auch auszugsweise, ohne schriftliche Genehmigung
  21. von Mulle KybernetiK weder reproduziert, übertragen umgeschrieben auf Da-
  22. tenträgern gespeichert oder in eine andere Sprache übersetzt werden, weder in
  23. mechanischer, elektronischer, positronischer, magnetischer, optischer, chemi-
  24. scher oder biologischer Form.
  25.  
  26. Geschrieben, gesetzt und gedruckt mit Tempus-WORD auf ATARI.
  27. 1. Auflage Mulle KybernetiK 1993, Bochum
  28. Printed in Germany
  29.  
  30. Mulle KybernetiK
  31. c/o Wallmann
  32. Buchenweg 2
  33. 5810 Witten-Buchholz
  34. Germany
  35.  
  36.  
  37.  
  38. 1-Der schnelle Weg zum Erfolg
  39.  
  40. Die nun folgenden "Wege zum Erfolg" reizen die Möglichkeiten der NAU-
  41. DIO-Bücherei bei weitem nicht aus. Wenn sie also über die hier vorgestell-
  42. te Funktionalität hinausgehen wollen, sollten sie das "Technische Manual"
  43. und das "Reference Manual" studieren.
  44.  
  45.  
  46. 1.1   Am Anfang war das Programm
  47.  
  48. und der Compiler sah, daß es gut war.
  49. Das folgende kleine Beispielprogramm demonstriert in ca. 50 Zeilen be-
  50. reits die wichtigsten Funktionen der NAUDIO-Bibliothek. Es mag durch-
  51. aus der Fall sein, daß sie nie weiter als dieses Kapitel lesen brauchen,
  52. wenn sie einfach nur auf relativ portable Art und Weise Samples auf allen
  53. möglichen Atari-Computern(1) abspielen wollen.
  54.  
  55. Zu Beginn einer C-Datei, die NAUDIO-Bibliotheken verwendet, sollte im-
  56. mer die Anweisung #include <naudio\naudio.h> stehen. Damit werden
  57. sämtliche für NAUDIO benötigten Includedateien geladen. Da wir fprintf
  58. für Demonstrationszwecke verwenden wollen, binden wir in diesem Bei-
  59. spiel (Reihenfolge übrigens unwichtig) auch noch die C-Standardbibli-
  60. othek <stdio.h> ein.
  61. Die Definition der Funktion error übergehen wir einstweilen und wenden
  62. uns gleich dem Hauptteil main zu:
  63.  
  64. #include <naudio\naudio.h>
  65. #include <stdio.h>
  66.  
  67. void  error( s)
  68. char  *s;
  69. {
  70.    fprintf( stderr, "demo: Error \"%s\"\n", s);
  71.    naudio_done();
  72.    exit( 1);
  73. }
  74.  
  75. main()
  76. {
  77.    n_sample    *p;
  78.  
  79.    naudio_init();
  80.    naudio_all();
  81.  
  82.    if( naudio_engine( SAMPLES) >= 0)
  83.    {
  84.       if( p = nsample_load( "zarths.smp"))
  85.       {
  86.          channel  *q;
  87.  
  88.          if( ! naudio_start( 0))
  89.          {
  90.             if( q = nsample_play( p, 0L, NAUDIO_MAX_VOL, 1))
  91.             {
  92.                while( q->play);/* warten auf Godot */
  93.                naudio_stop();
  94.                channel_free( q);
  95.             }
  96.             else
  97.                error( "Kein Kanal mehr vorhanden");
  98.             naudio_stop();
  99.          }
  100.          else
  101.             error( "Versagen des Starters");
  102.          nsample_free( p);
  103.       }
  104.       else
  105.          error( "Sample nicht geladen");
  106.       naudio_done();
  107.    }
  108.    else
  109.       error( "Engine nicht initialisiert");
  110.    return( 0);
  111. }
  112.  
  113. Zufürdererst sollte jedes NAUDIO-Programm die Routine naudio_init
  114. aufrufen. Diese setzt einige wichtige interne Werte, die für einen
  115. reibungslosen Ablauf von Nöten sind, nachdem sie die verfügbare
  116. Hardware analysiert hat. Danach sollten sie sich entscheiden ob sie alle
  117. Enginetypen einbinden wollen (naudio_all) oder nur die wichtigsten
  118. (naudio_some). Je weniger sie einbinden, desto kleiner wird auch ihre
  119. Programm, und in den meisten Fällen ist naudio_some völlig
  120. ausreichend.
  121.  
  122.    if( naudio_engine( SAMPLES) >= 0)
  123.  
  124. Danach wird das Audiosystem für das Abspielen von Samples durch
  125. naudio_engine vorbereitet. Der Rückgabewert ist bei Erfolg positiv oder
  126. 0, so daß wir jetzt beruhigt ein Sample aus einer Datei laden können. Bis
  127. jetzt findet noch keine Sounderzeugung statt!
  128.  
  129.    if( q = nsample_play( p, 0L, NAUDIO_MAX_VOL, 1))
  130.  
  131. Zum Laden eines Samples aus einer Datei verwendet man die Funktion
  132. nsample_load, die im Erfolgsfall einen Zeiger auf ein n_sample
  133. zurückgibt. Ein n_sample ist eine Struktur die Informationen über das
  134. Sample wie dessen Länge und dessen Samplewerte beinhaltet. (In main
  135. haben wir als erstes ein Zeiger auf ein solches n_sample definiert).
  136.  
  137. Nehmen wir an, daß das Sample tatsächlich geladen wurde (der Wert von
  138. p also nicht NULL ist), so wird als nächstes mit naudio_start das Sound-
  139. system angeworfen. Ab jetzt werden also Samplewerte an die Hardware
  140. ausgegeben. Da wir aber kein Sample zum Abspielen designiert haben,
  141. dürfte vorläufig immer noch nichts zu hören sein.
  142.  
  143.    if( q = nsample_play( p, 0L, NAUDIO_MAX_VOL, 1))
  144.  
  145. Mit nsample_play wird ein Kanal des Soundsystems reserviert und ein
  146. Sample auf ihm gespielt. Der Rückgabewert der Funktion ist ein Zeiger
  147. auf den reservierten Kanal. Auf einem solchen Kanal kann übrigens zu ei-
  148. nem Zeitpunkt immer nur ein monophones Sample gespielt werden.
  149. Das erste Argument der Funktion ist die Adresse des geladenen Sam-
  150. ples, welches wir spielen möchten (Im Beispiel: der Wert von p). Mit dem
  151. zweiten Parameter, den wir auf 0 gesetzt haben, legen wir fest, daß das
  152. Sample mit der Frequenz gespielt werden soll, mit der es aufgenommen
  153. wurde(2). Der dritte Parameter setzt die Lautstärke auf Maximum. Der
  154. vierte Parameter bedeutet nsample_play, daß mit dem Abspielen des
  155. Sample sofort begonnen werden soll.
  156. Über den ->play Eintrag des Kanals warten wir darauf, daß das Sample
  157. fertig ist. Natürlich könnte man hier auch noch etwas nützlicheres ma-
  158. chen, da das Sample, egal auf welcher Hardware, immer im Hintergrund
  159. gespielt wird. Solange ->play nicht 0 ist, wird das Sample noch
  160. gespielt.(3)
  161.  
  162. ACHTUNG: Wichtig ist die Unterscheidung zwischen geladenen Samples
  163. (n_sample) und den Kanälen des Soundsystems (channel). Die jeweili-
  164. gen Strukturen sind unterschiedlich und sollten nicht miteinander
  165. verwechselt werden.
  166.  
  167. Aus didaktischen Gründen schalten wir das Soundsystem mit nau-
  168. dio_stop nach Beendigung des Samples sofort wieder aus. Dies spart im
  169. übrigen auch in jedem Fall, auch auf dem STE oder Falcon, Prozessorzeit.
  170. Anschließend geben wir den Kanal mit channel_free wieder frei. Möchte
  171. man in eigenen Programmen mehrere Samples nacheinander spielen, so
  172. ist dies empfehlenswert(4), da naudio_play immer versucht einen neuen
  173. Kanal zu reservieren. Hat man aber nie einen Kanal zurückgegeben, ist ir-
  174. gendwann mal Schluß, da die Zahl der Kanäle auf acht beschränkt ist.
  175. Da wir mit dem Soundsystem nichts mehr vorhaben, können wir
  176. naudio_done aufrufen. Dieser Aufruf muß, nachdem naudio_engine(5)
  177. einmal aufgerufen wurde, vor Beendigung des Programms gemacht
  178. werden. Nichtbeachtung dieser Regel wird üblicherweise mit schweren
  179. Crashs nicht unter zwei Bomben bestraft.
  180. Wie man aus der Definition und Benutzung der error-Funktion im Bei-
  181. spielprogramm ersehen kann, ist ein überflüssiger Aufruf von nau-
  182. dio_done jedoch völlig unschädlich.
  183. Auch geladene Samples sollten sobald wie möglich der Wiederverwer-
  184. tung zugeführt werden, da Samples im allgemeinen speicherfressende
  185. Dinger sind. Eines mit nsample_load geladenes Samples entledigt man
  186. sich mittels nsample_free.
  187.  
  188.  
  189. 1.1.1 AUS!
  190.  
  191. Einen Kanal kann man auch vorzeitig mit channel_stop auschalten. Ein
  192. Ausschalten mit gleichzeitigem Freigeben erfolgt via channel_delete. Mit
  193. diesem Wissen können wir nun eine kleine C-Funktion schreiben,. die ein
  194. Sample aus einer Datei liest, dieses spielt und zurückkehrt, wenn entwe-
  195. der eine Taste auf dem Keyboard gedrüct wurde oder das Sample ver-
  196. klungen ist:
  197.  
  198. void load_n_play( char *filename)
  199. {
  200.    n_sample *p;
  201.    channel  *q;
  202.  
  203.    if( p = nsample_load( filename))/* laden, != 0 bei Erfolg */
  204.    {
  205.       if( q = nsample_play( p, 0L, NAUDIO_MAX_VOL, 1))/* spielen*/
  206.       {
  207.          while( q->play)/* so lange der channel aktiv ist */
  208.          {
  209.             if( Bconstat( 2))/* Taste gedrueckt ? */
  210.             {
  211.                Bconin(2);/* Taste einlesen & ignorieren */
  212.                channel_stop( q);/* ja, dann Kanal aus */
  213.                break;
  214.             }
  215.          }
  216.          channel_free( q);/* Kana